home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Almathera Ten Pack 2: CDPD 1
/
Almathera Ten on Ten - Disc 2: CDPD 1.iso
/
pd
/
076-100
/
085
/
lowmem
/
readme
< prev
next >
Wrap
Text File
|
1995-03-13
|
13KB
|
297 lines
ASDG Low Memory Server Documentation
Copyright 1987 By ASDG Incorporated
All Rights, Except Those Granted Herein, Reserved
1. Terms Of Distribution
-----------------------------------------------------------------------------
Permission for the non-commercial distribution of the ASDG Low Memory Server
is hereby granted. Non-commercial distribution is defined as distribution by
user groups, individuals not for profit, public service public domain disk
distributors (ie: my friend Fred Fish).
Any manufacturer of hardware or software is specifically enjoined from the
public distribution of any part of the Low Memory Server unless licensing
by ASDG is received.
The Low Memory Server is specifically NOT in the public domain.
2. Commercial Licensing
-----------------------------------------------------------------------------
ASDG encourages the commercial use of the Low Memory Server provided that
following provisions are affirmed and agreed upon by ASDG and the prospec-
tive licensee.
(a) The licensee agrees to credit ASDG Incorporated for the use of the Low
Memory Server in some reasonable visible fashion in the licensee's pro-
duct documentation,
(b) The licensee agrees to furnish ASDG with a finished product as it would
be purchased by the consumer.
Should ASDG find it necessary, a licensing fee of no more than $50 (U.S.)
may required in addition to the above. This fee is a one time expense and
shall be used to defray the cost of providing the license agreement.
3. What Is The ASDG Low Memory Server
-----------------------------------------------------------------------------
The ASDG Low Memory Server is a compact (900 bytes) shared library which al-
lows arbitrary processes to register their desire to be notified of impend-
ing memory shartages.
The purpose of the LMS is to allow for the easy notification of applications
that they should attempt to clean up or reduce their memory memory consumpt-
ion or face a complete absence of available memory.
For example, a graphics or sound editor may elect to be notified that memory
is becoming scare and if so notified will deallocate space used to hold
sounds or graphics no longer in current use by the user but which were re-
tained in ram as a performance boost in the event that the user would elect
to reuse the data at a later time.
The ASDG LMS provides a reliable low memory notification service which will
be tripped upon any failure of an AllocMem system call. Note: the ASDG LMS
uses operating system mechanics already present in 1.2 - it does not alter
or modify any system code - anywhere. Specifically, AllocMem is NOT touched.
Notification is performed via the natural interprocess communications prim-
itive available on the Amiga, the message.
Support for the ASDG LMS is intended to be coded into your application. The
remainder of this document is an explanation of how this is done.
4. As A Programmer, What Do You Agree To Do?
-----------------------------------------------------------------------------
You agree (by writing your code correctly) to the following things:
(a) You will allocate and initialize a message port to be used by the ASDG
LMS to notify you.
(b) You will allocate and initialize a LowMemMsg structure which will be
used BY the ASDG LMS to notify you.
(c) To be effective, you agree to monitor your LMS message port in all of
your calls to Wait.
(d) You agree to call DeRegLowMemReq when exiting, prior to closing the ASDG
LMS library.
(e) You agree to close the ASDG LMS library when done.
(f) You agree to reinitialize your LowMemMsg each time the ASDG LMS notifies
you of memory shortages.
(g) You agree to examine the return code from RegLowMemReq. This routine is
your interface to the Low Memory Server registration list. It will tell
you if the message port name you supplied has already been used by
someone else.
If you fail to do these things, there isn't much point in using the ASDG
LMS.
5. The LMS Message Port
-----------------------------------------------------------------------------
You must allocate and initialize a message port to which the LMS will send
you its low memory notification message. You may do this in the usual way.
However, you must be prepared to delete this message port and re-allocate it
as many times as is needed to get a unique message port name.
After defining the message port (with a name you hope will be unique) and
defining a LowMemMsg (see later) you will register your message port name
with the ASDG LMS by calling RegLowMemReq. This call may return an error
value indicating that the message port name is not unique. Your request to
register with the LMS has been denied and you must delete your message port
and redefine one with another name (and loop to the call to RegLowMemReq a-
gain).
This ensures that only one port with any given name will be registered with
the LMS.
6. The LowMemMsg
-----------------------------------------------------------------------------
YOU have to allocate a LowMemMsg structure. This will be the message that
LMS uses to notify you of a low memory condition.
You define it rather than the LMS since if the LMS needs to get in touch
with you, it is because there is a low memory situation present. Hardly the
time to go allocating message storage.
The LowMemMsg structure is defined in low-mem.h as is as follows:
struct LowMemMsg {
struct Message lm_msg;
long lm_flag;
};
This is simply a usual message structure with a long word flag tagged on the
end. The only initialization YOU have to do is to set the lm_flag to a spec-
ific value, LM_CONDITION_ACKNOWLEDGED. The LMS will initialize the rest of
the message for you.
Setting lm_flag to LM_CONDITION_ACKNOWLEDGED is cruicial to your receiving
messages from the LMS. Immediately prior to sending you a message the LMS
will (after verifying that your registered message port exists) interrogate
your lm_flag. If it is not set to LM_CONDITION_ACKNOWLEDGED then the LMS will
not send you the message.
You are specifically NOT to Reply to the message you receive from the LMS.
The LMS is being run directly from a failing AllocMem call by someone else's
program. To prevent the possibility of a program NOT replying to the LMS's
message (and thus deadlocking the system) I use the LM_CONDITION_ACKNOWLEDGED
value in lm_flag to signify that your process has acknolwedged the receipt of
its previous low memory message.
Repeat - DO NOT REPLY TO THE LOW MEMORY MESSAGE - SET lm_flag INSTEAD! Here's
the definition of LM_CONDITION_ACKNOWLEDGED:
#define LM_CONDITION_ACKNOWLEDGED (('A'<<24)|('S'<<16)|('D'<<8)|'G')
7. Requesting Registration
-----------------------------------------------------------------------------
After defining your message port to be used by the LMS to notify you of a
low memory situation and defining a LowMemMsg structure, you register your
message port and message structure with the ASDG LMS by calling the library
routine ``RegLowMemReq''.
The call takes the following form:
Result = RegLowMemReq(PortName , PtrToLowMemMsg);
d0 a0 a1
The call will return 0 if all went well. This return indicates that you
will be receiving low memory warnings through the specified port. If, how-
ever you do not receive a 0 result then something went astray with your
registration request.
Two error results are defined. These are:
#define LM_BADNAME -1 /* duplication of port name */
#define LM_NOMEM -2 /* memory allocation failed */
If you receive LM_BADNAME then the ASDG LMS is telling you that someone has
previously registered the same port name as you have just tried. Simply
change the name and resubmit the request (taking into account the fact that
you might have already allocated a port with the invalid name).
The following flow chart indicates a reasonable way to choose a port name:
Forbid()
|
|
Choose A Name <----------\-----\
| | |
| | |
FindPort | |
| | |
| (yes) | |
Port Already Defined?--------/ |
| |
| (no) |
| |
RegLowMemReq |
| |
| (yes) |
(Note 1)---------->Fail?----------------------/
|
| (no)
|
CreatePort
|
|
Permit
|
v
Note 1: This can happen since someone may have DeletePort'ed their message
port but NOT canceled their reservation with the LMS by calling
DeRegLowMemReq.
8. Requesting DeRegistration
-----------------------------------------------------------------------------
As part of your program's exit process you should cancel your registration
with the LMS. This is done by calling DeRegLowMemReq with the LMS port name
as the only argument. If you do not call this routine before exiting AND
some other process still has the LMS library open, the memory that the LMS
library allocated to store your registration will not be freed.
However, when the last process that has the LMS library open finally does
close it, all remaining nodes (from people who didn't call DeRegLowMemReq)
will be expunged along with the rest of the library.
Summary of call:
(void) DeRegLowMemReq(PortName);
a0
9. Closing The LMS Library
-----------------------------------------------------------------------------
It is absolutely critical that your close the LMS library before exiting
your program. If you don't, the library's open count can never again go to
zero causing the library to be unable to expunge itself from memory when
otherwise no longer needed. While the LMS is very compact this is still not
a wise thing to do.
The LMS library is closed in the following way:
CloseLibrary(LowMemBase);
Note that the long integer LowMemBase must be declared somewhere in your ap-
plication using the above spelling.
10. The lm_flag Again...
-----------------------------------------------------------------------------
This chapter is here JUST to remind you that the LMS will look for a specif-
if value in your lm_flag LowMemMsg field. If lm_flag is not LM_CONDITION_-
ACKNOWLEDGED, then the LMS will not send you any more messages.
11. Hints For Using The ASDG LMS Effectively
-----------------------------------------------------------------------------
If AllocMem detects that it is going to fail due to lack of memory, it will
run the list of libraries calling each library's expunge routine in turn.
The LMS upon having its expunge routine tickled will run through its list
of registrations sending off messages to each registers message port in
turn (the last thing you want here is to have LMS wait for a reply so it is
written specifically NOT to - so don't reply to any messages that the LMS
may send you).
Some calls to AllocMem fail even when there's plenty of memory available.
For example, a request to AllocMem for 2 megabytes of memory on a 512K
Amiga will certainly fail even though there might be 400K still available.
To really use the LMS effectively, the first thing your program should do
is to actually interrogate the amount of memory available on the system by
calling AvailMem. Thus, your program can tell the difference between a real
memory emergancy and an AllocMem whose goals were unrealistic.
12. About The ASDG LMS
-----------------------------------------------------------------------------
The ASDG Low Memory Server was written completely in Manx Assembly Language
by Perry S. Kivolowitz, president of ASDG Incorporated. The LMS was written
as part of the development of ASDG's update to Facc, FaccII. FaccII is a
floppy accelerator providing performance from floppy disk far in excess of
current hard disks (with some limitations of course).
FaccII will use the LMS to determine when it should begin taking memory
conservation measures.
While FaccII is a commercial product, we have decided to release the LMS
for non-commercial distribution (and licensed commercial distribution) be-
we view the LMS as a useful generic tool which we feel the Amiga community
as a whole would benefit from and, of course, we felt that doing this would
be in the best interest of ASDG (besides why have everyone write their own
and possibly have several of them running on the machine at once?)
We feel ASDG has contributed as much to the betterment of the Amiga commun-
ity as any other vendor or private contributor. The ASDG Recoverable Ram
Disk, tutorials in Amazing Computing, and now the LMS are examples of our
love and committment for the Amiga personal computer and the Amiga using
community. This is our small way of showing that, yes, we put back in and
not just take out.